Short:    Create .cd file from running program
Author:   thomas-rapp@web.de (Thomas Rapp)
Uploader: thomas-rapp@web.de (Thomas Rapp)
Version:  0.2
Type:     dev/misc
Requires: AmigaOS 2.1+


Introduction
============

Did you ever download or even buy a program and the author promised to
deliver some language catalogs but didn't do so for a long time ?

Then this is the solution for you: UnCat patches the locale.library 
and catches all calls to it concerning translation. Then it creates
a .cd file which you can use to create a new language catalog file.

Note: UnCat can only be used with programs that are already prepared
      to be localised and use locale.library. It is not meant for 
      developers that want to create localisation for their program.

Patched functions:

   OpenCatalogA   for the catalog name and version

   GetCatalogStr  for the string IDs and builtin strings


New in Release 2
================

- Fixed some enforcer Hits. Strings are now copied to the message instead
  of using pointers into foreign memory.


Disclaimer
==========

  - The program is Freeware. Please do not distibute the program without
    the readme file.

  - The program was only tested by me on my machine. There is no guarantee 
    that it runs on others. I am not responsible for any damage. Use it on 
    your own risk.

  - It might not be legal to reengineer someone's program in the way UnCat 
    does, in order to translate its strings to another language. I am not
    reponsible for any actions that others do with my program.

  - I would be very pleased if you send me german catalog files that you
    created using my program.


Installation
============

Copy the UnCat executable to your C: directory or to some other place
in your DOS path.


Procedure
=========

- Read the "Important" section of this readme !!!

- Start UnCat naming the program you want to monitor and the .cd file
  you want to create.

- Start the program and use it. Try to see as many strings as possible.
  Only strings that are referred by the program will appear in the
  .cd file.

- Stop UnCat.

- Use the created .cd file to create a new language catalog file.


Usage
=====

UnCat must be called from a Shell window. When called, UnCat installs
its patches and then waits. When you press Ctrl-C, the patches are 
removed and UnCat is stopped.


Parameters
==========

TASK/A       Pattern for the task name to be monitored. May contain
             AmigaDOS wildcards.

FILE/A       Filename to be written containing the catalog description.
             Should end with .cd

MAXID/N      If the .cd file contains duplicate string IDs, the monitored
             program uses more than 5000 strings. Use this parameter to enter
             a number greater than 5000.


Example:  uncat #?miamidx#? translations/miamidx.cd


Important
=========

- Start UnCat only once at a time !!!

- Don't use any other program that patches locale.library while UnCat is
  running !!!

- The first line of the .cd file contains the catalog name and version. The
  new catalog must be named exactly this way. If the version number is not 0
  (zero) the new catalog must have exactly this version.

  Example: if the first line is

   ; xyz.catalog Version 2

   your new catalog must be named xyz.catalog and contain a version string like

   $VER: xyz.catalog 02.00 (20.04.01)


- The strings in the .cd file are ordered by appearence, not by number. So this
  could be a little confusing.

- UnCat runs asynchronously and uses pointers into the monitored program's
  memory, so this could lead to crashes. If the monitored program crashes,
  you can still stop UnCat and use the .cd file. If UnCat crashes, bad luck.
  Please tell me the program you monitored and the action you did before the
  crash.

- If your .cd file remains empty, the TASK pattern you entered did not match. 
  Try enclosing it in #?. For DOS processes (Shell windows) the program name
  like entered in the DOS window or Shell script is used, including path. For 
  workbench tasks only the program name like shown below the icon is used.

- If the monitored program uses localised system functions (like file requestors
  or system failures) those stings might apear in the .cd file. Try to remove
  them as they are misplaced here.


Messages
========

invalid pattern for task

    The pattern you entered for TASK contains an error. Correct it and try
    again.


cannot create port

    UnCat could not create a message port. Usualy not enough memory (see there).


not enough memory

    The number you entered for MAXID is too large. UnCat needs four times of
    MAXID bytes of memory. If you didn't enter MAXID, try a number smaller than
    5000 for MAXID.


cannot open output file

    The file you specified as destination could not be opened. Correct the 
    file name and try again.


uncat installed
press Ctrl-C to quit

    UnCat has installed its patches and is waiting for incoming messages.


invalid message received

    Some other program is using UnCat's message port. Should never happen.


uncat ended

    This message is issued always before exiting, showing a normal end of
    the program.


============================= Archive contents =============================

Original  Packed Ratio    Date     Time    Name
-------- ------- ----- --------- --------  -------------
    8492    5526 34.9% 15-Jul-01 11:51:10  uncat
    5202    2233 57.0% 15-Jul-01 11:57:44  uncat.readme
-------- ------- ----- --------- --------
   13694    7759 43.3% 16-Jul-101 20:03:36   2 files
